home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir24 / bpq408.zip / BPQHOST.DOC < prev    next >
Text File  |  1994-03-26  |  10KB  |  392 lines
  1.             G8BPQ Host Mode
  2.  
  3. From Version 4.00, a new application interface to the switch is provided.
  4. This replaces the existing interfaces (TNC2, PK Host and KISS). New
  5. software should if possible use the new interface - interface routines
  6. supporting the old modes, and WA8DED Host mode, will be provided as TSRs
  7. to support existing application software.
  8.  
  9. The interface is normally called using INT 7Fh. From version 4.03 the interrupt
  10. number may be changed - The value is specified in BPQCFG.TXT as INTERRUPT=nnn,
  11. where nnn is in decimal. The function required is in AH, and the stream in AL.
  12. The system supports 64 streams, or sessions, numbered from 1 - 64.
  13.  
  14. Changes in Version 4.05.
  15.  
  16. 1.    Additional option on funtion 6 - allows connects using BBS Call, even
  17.     if APPLMASK is not set (say to prevent connects).
  18.  
  19. 2.    Additional info returned by function 8.
  20.  
  21. 3.    Format of frame returned by function 11 added to documentation.
  22.  
  23. 4.    Function 15 added. Simplifies access to timing info.
  24.  
  25. 5.     Broadcast option added. If function 2 is called with AL=0, the
  26.     data will be sent as a UI frame to all ports which have an UNPROTO
  27.     address set.
  28.  
  29. 6.     Function 12 added to update Beacon text. 
  30.  
  31.  
  32. Changes in Version 4.07b
  33.  
  34. 1.     Function 0 added to check if loaded, and get version number. This
  35.     is because the old method of checking (looking at the bytes before
  36.     the interrupt routine) isn't compatible with some versions of
  37.     DesqView, or the Windows version of the switch (coming soon!)
  38.  
  39. 2.    Function 12 extended to allow application to request a NODES
  40.     broadcast.
  41.  
  42. 3.    Function 13 added to allow application to request a free stream and
  43.     to free a stream after use. This will simplify configuration when
  44.     several applications are used.
  45.  
  46.  
  47. Note that in all cases where a string is returned, ES:DI must point to
  48. a buffer supplied by the user, and the switch will copy the data to 
  49. this buffer. The code does NOT return pointers to its own data.
  50.  
  51.  
  52.     AH = 0    Get node/switch version number and description.  On return
  53.         AH='B',AL='P',BH='Q',BL=' '
  54.         DH = major version number and DL = minor version number
  55.  
  56.  
  57.     AH = 1    Set application mask to value in DL.
  58.         Set application flags to value in CL.
  59.           If top bit of CL is set, monitored frames will be available.
  60.           Use function 11 to receive them. 
  61.  
  62.     AH = 2    Send frame in ES:SI (length CX)
  63.  
  64.  
  65.     AH = 3    Receive frame into buffer at ES:DI, length of frame returned
  66.         in CX.  BX returns the number of outstanding frames still to
  67.         be received (ie. after this one) or zero if no more frames
  68.         (ie. this is last one).
  69.         Note that CX is NOT an input param - the supplied buffer
  70.         must be big enough to receive a full AX.25 frame, including
  71.         up to 8 digi callsigns. 340 should be enough.
  72.  
  73.  
  74.     AH = 4    Get stream status.  Returns:
  75.  
  76.         CX = 0 if stream disconnected or CX = 1 if stream connected
  77.         DX = 0 if no change of state, or DX = 1 if
  78.                the connected/disconnected state has changed.
  79.  
  80.     AH = 5    ACK stream status change. Must be called to allow another
  81.         status change to be reported. 
  82.  
  83.  
  84.     AH = 6    Session control.
  85.  
  86.         CX = 0 Connect to Node. Session uses BBS callsign if bottom
  87.                     bit of DL=1, otherwise uses Node Call .
  88.  
  89.         CX = 1 Connect to Node. Session uses BBS Call if APPLMASK=1,
  90.                     otherwise Node Call.
  91.  
  92.         CX = 2 Disconnect
  93.         CX = 3 Return user to node
  94.  
  95.  
  96.     AH = 7    Get buffer counts for stream.  Returns:
  97.  
  98.         BX = number of frames queued for receive
  99.         CX = number of un-acked frames to be sent
  100.         DX = number of buffers left in node
  101.  
  102.  
  103.     AH = 8    Port control/information.  Called with a stream number
  104.         in AL returns:
  105.  
  106.         ES:DI = CALLSIGN (10 bytes space padded)
  107.  
  108.         The following are now supported (4.05 onwards)
  109.  
  110.         AL = Radio port on which channel is connected (if level 2)
  111.         AH = Session Type (If Connected). Session type bits are:
  112.  
  113.            L2LINK    EQU    1
  114.            SESSION    EQU    10B
  115.            UPLINK    EQU    100B
  116.            DOWNLINK    EQU    1000B
  117.            BPQHOST    EQU    100000B
  118.     
  119.         BX = L2 paclen for the session
  120.         CX = Maxframe. Taken from PORT maxframe if L2 session,
  121.              Switch maxframe if L4.
  122.         DX = L4 window size (if L4 circuit, or zero)
  123.  
  124.  
  125.     AH = 10    RAW (KISS) transmit frame.  Data pointed to by ES:SI, of
  126.         length CX, is transmitted as a HDLC frame on the radio
  127.         port (not stream) in AL.
  128.  
  129.  
  130.     AH = 11 Get Trace (RAW Data) Frame into ES:DI, Length to CX. Data
  131.         is as received off air (ie with calls in AX.25 format, etc)
  132.         See note on CX under function 3.
  133.  
  134.         The returned buffer includes a 5 byte header:
  135.  
  136.             Bytes 0-1  - Internal control info (ignore)
  137.             Byte  2    - Port number. Top bit set if transmitted frame.
  138.             Bytes 3-4  - Frame length (including this header)
  139.  
  140.  
  141.     AH = 12 Update Switch Info. This will be used for a number of
  142.         operations. At the moment the only ones implemented are to
  143.         update the Beacon Text field, and initiate a NODES broadcast.
  144.  
  145.         DX = Function Number.
  146.         
  147.            DX = 1  Update Beacon Text.
  148.  
  149.             ES:SI Data to send in Beacons
  150.             CX    Length of Data
  151.  
  152.            DX = 2  Initiate NODES broadcast
  153.  
  154.     AH = 13 Allocate/deallocate stream
  155.  
  156.         If AL=0, return first free stream in AL. If AL=255 on
  157.            return, there are no free streams
  158.  
  159.         If AL>0, CL=1, Allocate stream. If aleady allocated,
  160.            return CX nonzero, else allocate, and return CX=0
  161.  
  162.         If AL>0, CL=2, Release stream
  163.  
  164.        Note that for compatiblity with old software, certain other
  165.        functions also set the allocated bit (Functions 1,2,6). So
  166.        an application has a reasonable chance of getting an unused
  167.        stream, even if some applications dont use the allocate function.
  168.  
  169.  
  170.         AH = 15 Get time marker in AX. Value is number of timer interrupts
  171.         since switch was loaded, modulo 65536. Timer interrupts 
  172.         normally occur at approx 18.2 per second.
  173.  
  174.  
  175.  
  176.  
  177. PACLEN.
  178.  
  179. Frames are transmitted as received from the application, so the application
  180. is responsible for the transmitted PACLEN. Function 8 will return the
  181. recommended value for the current session. I think the value is always OK,
  182. but I suggest you treat a value of zero as 'undefined', and use your own
  183. default. The value may change during a session, if for instance, you connect
  184. to the switch, and then out on a port with a different PACLEN. Also at
  185. some time in the future I hope to adjust PACLEN to suit conditions on the
  186. channel. So I recommend that the value is re-read from time to time during
  187. a session.
  188.  
  189.  
  190.  
  191. The following sample of code shows how to find the Interrupt Number to use
  192. to call the switch, and check that the switch is loaded.
  193.  
  194.  
  195. NOTBPQERROR    DB    'Switch not found$'
  196. VERSERROR    DB    'Version not compatible with Node Software$'
  197.  
  198. BADCONFIGMSG    DB    'Configuration file read error',0DH,0AH,'$'
  199. CONFIGFILENAME    DB    'BPQCFG.BIN',0
  200. NOCONFIGMSG    DB    'Configuration file BPQCFG.BIN not found',0DH,0AH,'$'
  201. ;
  202. ;    BPQCFG FIRST 128 BYTES
  203. ;
  204. CONFIGTABLE    LABEL    BYTE
  205. ;
  206. ;    CONFIGURATION DATA STRUCTURE
  207. ;
  208. ;    DEFINES LAYOUT OF CONFIG RECORD PRODUCED BY CONFIGURATION PROG
  209. ;
  210. ;    LAYOUT MUST MATCH THAT IN CONFIG.C SOURCE
  211. ;
  212. C_NODECALL    DB    10 DUP (0)     ; OFFSET = 0 
  213. C_NODEALIAS    DB    10 DUP (0)     ; OFFSET = 10
  214. C_BBSCALL    DB    10 DUP (0)     ; OFFSET = 20
  215. C_BBSALIAS    DB    10 DUP (0)     ; OFFSET = 30
  216. ;
  217. C_OBSINIT    DW    0         ; OFFSET = 40
  218. C_OBSMIN    DW    0         ; OFFSET = 42
  219. C_NODESINTERVAL    DW    0         ; OFFSET = 44
  220. C_L3TIMETOLIVE    DW    0         ; OFFSET = 46
  221. C_L4RETRIES    DW    0         ; OFFSET = 48
  222. C_L4TIMEOUT    DW    0         ; OFFSET = 50
  223. C_BUFFERS    DW    0         ; OFFSET = 52
  224. C_PACLEN    DW    0         ; OFFSET = 54
  225. C_TRANSDELAY    DW    0         ; OFFSET = 56
  226. C_T3        DW    0         ; OFFSET = 58
  227.            DW    0         ; OFFSET = 60
  228.         DW    0         ; OFFSET = 62
  229. C_IDLETIME    DW    0         ; OFFSET = 64
  230. C_EMSFLAG    DB    0         ; OFFSET = 66
  231.         DB    0
  232. C_BBS        DB    0         ; OFFSET = 68
  233. C_NODE        DB    0         ; OFFSET = 69
  234. C_HOSTINTERRUPT    DB    0         ; OFFSET = 70
  235. C_DESQVIEW    DB    0         ; OFFSET = 71
  236. C_MAXLINKS    DW    0         ; OFFSET = 72
  237. C_MAXDESTS    DW    0
  238. C_MAXNEIGHBOURS    DW    0
  239. C_MAXCIRCUITS    DW    0        ; 78
  240.  
  241. C_TNCPORTLISTO    DB    16 DUP (0)     ; OFFSET = 80
  242.  
  243. C_IDINTERVAL    DW    0        ; 96
  244. C_XXXXXXXX    DW    0        ; 98    ; SPARE (WAS DIGIFLAG)
  245. C_MINQUAL    DW    0        ; 100
  246. C_HIDENODES    DB    0        ; 102
  247. C_L4DELAY    DW    0        ; 103
  248. C_L4WINDOW    DW    0        ; 105
  249. C_BTINTERVAL    DW    0        ; 106
  250. X_UNPROTO    DB    9 DUP (0)    ; 108    ; NOW SPARE
  251. C_BBSQUAL    DW    0        ; 117
  252.         DB    (CONFIGTABLE+128-$) DUP (0)
  253.  
  254.  
  255.  
  256. CONFIGHANDLE    DW    0
  257.  
  258. NODE:
  259.     INT    7FH
  260.     RET
  261.  
  262.  
  263. INIT:
  264. ;
  265. ;    GET NODE INTERRUPT NUMBER FROM CONFIG FILE
  266. ;
  267.     MOV    DX,OFFSET CONFIGFILENAME
  268.     MOV    AH,3DH
  269.     MOV    AL,0            ; READ ONLY
  270.     INT    21H            ; OPEN IT
  271.  
  272.     JC    NOCONFIGFILE
  273.  
  274.     MOV    CONFIGHANDLE,AX
  275.  
  276.     MOV    BX,AX
  277.     MOV    DX,OFFSET CONFIGTABLE
  278.     MOV    CX,128
  279.     MOV    AH,3FH
  280.  
  281.     INT    21H            ; READ
  282.     CMP    AX,CX
  283.     JNE    SHORTCONFIG
  284.  
  285.     JMP SHORT PROCESSCONFIG
  286.  
  287. NOCONFIGFILE:
  288.  
  289.     MOV    DX,OFFSET NOCONFIGMSG
  290.     JMP SHORT CONFIGERR
  291.  
  292. SHORTCONFIG:
  293.  
  294.     MOV    DX,OFFSET BADCONFIGMSG
  295.  
  296. CONFIGERR:
  297.  
  298.     MOV    AH,9
  299.     INT    21H
  300.  
  301.     MOV    AX,4C01H
  302.     INT    21H            ; EXIT
  303.  
  304. PROCESSCONFIG:
  305.  
  306.     MOV    BX,CONFIGHANDLE
  307.     MOV    AH,3EH
  308.     INT    21H            ; CLOSE IT
  309.  
  310.     MOV    AL,C_HOSTINTERRUPT    ; INTERRUPT
  311.     MOV    BYTE PTR NODE+1,AL    ; PATCH NODE CALL INSTRUCTION
  312. ;
  313. ;    GET NODE VERSION
  314. ;
  315.     PUSH    DS
  316.     MOV    AH,0
  317.     ADD    AX,AX            ; VECTORS ARE 4 BYTES LONG
  318.     ADD    AX,AX
  319.     MOV    SI,AX
  320.  
  321.     XOR    AX,AX
  322.     MOV    DS,AX
  323. ;
  324. ;    DS:SI POINTS OUR VECTOR
  325. ;
  326. ;    FIRST SEE IF VECTOR POINTS TO CODE - CALLING AN UNINITIALISED
  327. ;    INTERRUPT WILL CRASH THE SYSTEM
  328. ;
  329.     CMP    WORD PTR DS:2[SI],0    ; INTERRUPT ROUTINE SEGMENT ADDRT
  330.  
  331.     POP    DS
  332.  
  333.     JNE    SWITCHOK        ; ROUTINE PRESENT
  334.  
  335. NOSWITCH:
  336.  
  337.     MOV    DX,OFFSET NOTBPQERROR
  338.  
  339.     MOV    AH,9
  340.     INT    21H
  341.  
  342.     JMP SHORT EXIT
  343.  
  344. SWITCHOK:
  345.  
  346.     MOV    AH,0
  347.     CALL    NODE            ; SET INSTALLED FLAGS AND VERSION
  348.  
  349.     CMP    AX,'PB'            ; AX,BX SHOULD BE 'BPQ '
  350.     JNE    NOSWITCH
  351.  
  352.     CMP    BX,' Q'
  353.     JNE    NOSWITCH
  354.  
  355.     CMP    DH,MAJORVERSION
  356.     JNE    BADVERSION
  357.  
  358.     CMP    DL,MINORVERSION
  359.     JE    VERSIONOK
  360.  
  361.  
  362. BADVERSION:
  363.  
  364.     POP    DS
  365.  
  366.     MOV    DX,OFFSET VERSERROR
  367.     MOV    AH,9
  368.     INT    21H
  369.  
  370. EXIT:
  371.     MOV    AX,4C00H
  372.     INT    21H
  373.  
  374. VERSIONOK:
  375.  
  376.     POP    DS
  377. ;
  378.     ..........
  379.  
  380.  
  381.  
  382. The release disk also contains a demonstration terminal program, TERM4,
  383. written by G8IMB (in PASCAL) to demonstate the use of the new interface from
  384. a high level language. Note, however, that it was written for version 4.02,
  385. and therefore only works with the Host Mode interrupt configured at 7Fh
  386.  
  387.  
  388.  
  389. John Wiseman, G8BPQ @ GB7BAD
  390. 20/12/91
  391. Revised 5/9/92 and 26/3/94
  392.